Message Transactions

vFire has two Application Programming Interfaces (or APIs), which enable you to develop programs that automate many common vFire transactions. This section of the documentation deals with the Classic API. For more information on the RESTful Alemba API, introduced in 9.7, see here.

The Classic API provides a number of generic messaging transactions.

Most email transactions also provide internal message and pager support.  The bEmail, bInternal and bPager options allow you to specify which message types you want to send. 

Recipients must have the correct permissions and settings to receive emails/internal messages and pagers.

For most messaging transactions, you can specify two parameters that the message template uses. The nMessageMapRef parameter is a reference to the HD_MESSAGE_MAP table.  This specifies the message template as well as the message type and query to use. The nMessageType parameter is a vFire message type number.  From this, the API will find the default template and query.

Similarly, the pager message type and map options will define the template to use.

For a list of message types used by the API, see Message Types.

MessageSendMessage Transaction

The SendMessage transaction can be used to send messages to selected recipients from a selected email address. This transaction can only send the message.

Input Parameters: MessageRequest

Argument

Type

Mandatory

Default

Description

sID

String

No. See Transaction Login.

“”

Analyst’s current Session ID

sLoginUserID

String

No. See Transaction Login.

“”

Analyst’s Login ID

sLoginPassword

String

No. See Transaction Login.

“”

Analyst’s Password

sDatabase

String

No. See Transaction Login.

“”

Name of the vFire system for logging in.

sFromEmailID

String

No

Sending analyst’s email address

From Email ID

lSentBy

Lookup Field

No

Analyst calling transaction

Analyst sending the message

eEntityType

Enumerated

Yes

-

Entity from which to send the email. Values:

  • Call
  • Request
  • Task
  • Bulletin
  • Knowledge
  • CMDB item

nEntityRef

Integer

Yes

-

Number of the entity (e.g. call, request, CMDB item) from which to send the email.

ePriority

Enumerated

No

No Priority

Priority associated with the email sent. Values:

  • No Priority
  • Lowest
  • Low
  • Normal
  • High
  • Highest

sSubject

String

No

“”

Subject line of the email sent

eMMAMessageType

Enumerated

No

None

MMA Message Type. Values:

  • None
  • Call
  • Request
  • Task
  • Question
  • Approval
  • Placeholder (not relevant to the API)

nMessageMapRef

Integer

No

None

Reference to the HD_MESSAGE_MAP table.  This specifies the message template as well as the message type and query to use.

nMessageType

Integer

No

None

vFire message type to use for this email.

eFormat

Enumerated

No

System default email out format

Email format. Values:

  • Plain Text
  • HTML
  • Related HTML

nPagerMapRef

Integer

No

None

Reference to the HD_PAGER_MAP table. This specifies the pager template as well as message type and query to use.

nPagerType

Integer

No

None

vFire pager type to use for this message.

lRecipientRef

Lookup Field

Yes

-

Recipient of the email

eRecipientType

Enumerated

Yes

-

Type of receipient to which to send the email. Values:

  • IPK Group
  • Workflow Group
  • Person

bEmail

Boolean

No

False

Indicate whether to send an email to the intended recipient. Values:

  • True = send email
  • False = do not send email

bInternal

Boolean

No

False

Indicate whether to send an internal message to the intended recipient. Values:

  • True = send internal message
  • False = do not send internal message

bPager

Boolean

No

False

Indicate whether to send a pager message to the intended recipient. Values:

  • True = send pager message
  • False = do not send pager message

aCustomParameters

Array

No

“”

See Defining Custom Parameters.

Return Values: MessageResponse

Argument

Type

Description

sMessage

String

Error/Warning message returned from the API Transaction

nRet

Integer

Error/warning number returned from the API Transaction

MessageSendMessageByTemplate Transaction

Input Parameters: MessageByTemplateRequest

Argument

Type

Mandatory

Default

Description

sID

String

No. See Transaction Login.

“”

Analyst’s current Session ID

sLoginUserID

String

No. See Transaction Login.

“”

Analyst’s Login ID

sLoginPassword

String

No. See Transaction Login.

“”

Analyst’s Password

sDatabase

String

No. See Transaction Login.

“”

Name of the vFire system for logging in.

sTemplateName

String

Yes

-

Message template to use to send the message

sSubject

String

No

“”

Subject line of the email sent

ePriority

Enumerated

No

No Priority

Priority associated with the email sent. Values:

  • No Priority
  • Lowest
  • Low
  • Normal
  • High
  • Highest

lRecipientRef

Lookup Field

Yes

-

Recipient of the email

eRecipientType

Enumerated

Yes

-

Type of receipient to which to send the email. Values:

  • IPK Group
  • Workflow Group
  • Person

sEmailID

String

Yes

-

To Email ID

lSentBy

Lookup Field

No

Sending analyst’s email address

Analyst sending the message

sFromEmailID

String

No

Analyst calling transaction

From Email ID

nEntityRef

Integer

Yes

-

Number of the entity (e.g. call, request, CMDB item) from which to send the email.

eMMAMessageType

Enumerated

No

None

MMA Message Type. Values:

  • None
  • Call
  • Request
  • Task
  • Question
  • Approval
  • Placeholder (not relevant to the API)

bEmail

Boolean

No

False

Indicate whether to send an email to the intended recipient. Values:

  • True = send email
  • False = do not send email

bInternal

Boolean

No

False

Indicate whether to send an internal message to the intended recipient. Values:

  • True = send internal message
  • False = do not send internal message

bPager

Boolean

No

False

Indicate whether to send a pager message to the intended recipient. Values:

  • True = send pager message
  • False = do not send pager message

aCustomParameters

Array

No

“”

See Defining Custom Parameters.

Return Values: MessageResponse

See MessageResponse for more information.

MessageStakeHolders Transaction

Input Parameters: MessageStakeHoldersRequest

Argument

Type

Mandatory

Default

Description

sID

String

No. See Transaction Login.

“”

Analyst’s current Session ID

sLoginUserID

String

No. See Transaction Login.

“”

Analyst’s Login ID

sLoginPassword

String

No. See Transaction Login.

“”

Analyst’s Password

sDatabase

String

No. See Transaction Login.

“”

Name of the vFire system for logging in.

sFromEmailID

String

No

Sending analyst’s email address

From Email ID

lSentBy

Lookup Field

No

Analyst calling transaction

Analyst sending the message

eEntityType

Enumerated

Yes

-

Entity from which to send the email. Values:

  • Call
  • Request
  • Task
  • Bulletin
  • Knowledge
  • CMDB item

nEntityRef

Integer

Yes

-

Number of the entity (e.g. call, request, CMDB item) from which to send the email.

ePriority

Enumerated

No

No Priority

Priority associated with the email sent. Values:

  • No Priority
  • Lowest
  • Low
  • Normal
  • High
  • Highest

sSubject

String

No

“”

Subject line of the email sent

eMMAMessageType

Enumerated

No

None

MMA Message Type. Values:

  • None
  • Call
  • Request
  • Task
  • Question
  • Approval
  • Placeholder (not relevant to the API)

eRecipientTypes

Enumerated

Yes

-

Type of receipient to which to send the email. Values:

  • IPK Group
  • Workflow Group
  • Person

nMessageMapRef

Integer

No

None

vFire message type to use for this email.

nMessageType

Integer

No

System default email out format

Email format. Values:

    Plain Text

    HTML

    Related HTML

eFormat

Enumerated

No

System default email out format

Email format. Values:

  • Plain Text
  • HTML
  • Related HTML

nPagerMapRef

Integer

No

None

Reference to the HD_PAGER_MAP table. This specifies the pager template as well as message type and query to use.

nPagerType

Integer

No

None

vFire pager type to use for this message.

bEmail

Boolean

No

False

Type of recipient to which to send the email. Values:

  • IPK Group
  • Workflow Group
  • Person

bInternal

Boolean

No

False

Indicate whether to send an email to the intended recipient. Values:

  • True = send email
  • False = do not send email

bPager

Boolean

No

False

Indicate whether to send an internal message to the intended recipient. Values:

  • True = send internal message
  • False = do not send internal message

aCustomParameters

Array

No

False

Indicate whether to send a pager message to the intended recipient. Values:

  • True = send pager message
  • False = do not send pager message

Return Values: MessageResponse

See MessageResponse for more information.